


























                                     SUBMERGE

                                   Version  2.0


























                     COPYRIGHT (C) 1988 by STRATFORD INSTITUTE

   Joseph J. Bruns         1220 Stratford Lane          Hanover Park, IL 60103













  SUBMERGE is a shareware program.  You are encouraged to try the program out.
  If you find it helpful and intend to keep it, you are requested to send $10
  to the author to help support the past and future development of the program.
  This concept allows you to try a program without investing money, sometimes
  only to find out that the program is useless to you.  If you do like the
  program, however, the investment is minimal.

  Shareware authors will continue to provide you with such programs ONLY if you
  support them.  Please send your contribution, along with any suggestions you
  may have for improvements or for future programs to:

                            Joseph J. Bruns
                            1220 Stratford Lane
                            Hanover Park, IL 60103

  Please include your name and address so that you can be notified of any fixes
  or patches which might be necessary.

                       ------------------------------


                                  OVERVIEW


  SUBMERGE is a set of assembly language subroutines which can be merged with
  a BASIC program.  The routines reside in protected high memory, where they
  can be CALLed from the BASIC program.  They perform tasks which are either
  impossible or very difficult to perform with BASIC alone, allowing you to
  write better programs more efficiently.

  The routines allow you to do such things as turn the CAPS lock on and off,
  disable the BREAK key, scroll protect up to 7 lines at the top of the screen,
  change the cursor character and instantly print one of two full screens
  created by SUBMERGE's screen editor or menu generator.  There is also an easy
  to use formatted input routine.  Once installed, SUBMERGE allows your BASIC
  program to perform these routines with a simple CALL instruction, such as:

     30 CALL CAPS(YES)

  which will cause any keyboard entries to be in upper case (unless the CAPS
  lock key is pressed afterward).

  NOTE: In the examples which follow, parameters are sometimes passed to the
  routine (such as the 'YES' in the above example).  These parameters must be
  INTEGERS in order for the routines to work correctly.  If you do not define
  the parameters as integers with the DEFINT statement, then append a % sign at
  the end, such as:

     30 CALL CAPS(YES%)

  The name of the routine (such as 'CAPS' in the above example) does not,
  however, have to be an integer.


                                        1











                                  ROUTINES


  Following is a list of the routines available to your BASIC program from
  SUBMERGE.  The proper syntax for each routine is described.


  BREAK

  To disable the BREAK key, 'CALL BREAK(NO)'.  Be careful to use this only
  after your program has been de-bugged, as you will not be able to break out
  of the program.  To re-enable the BREAK key, 'CALL BREAK(YES)'.


  CAPS

  If you want upper case input, 'CALL CAPS(YES)'.  For lower case input, 'CALL
  CAPS(NO)'.  Any subsequent keyboard entries will be of the appropriate case,
  unless the CAPS lock key is pressed after calling this routine.


  CURSOR

  To change the cursor character, assign a value equal to the character code to
  an integer and use that integer as a parameter.  For example, if you want to
  change the cursor to a solid block, such as CHR$(143), then use something
  like 'N=143 : CALL CURSOR(N)'.  To change it back to the original underline
  character use 'X=95 : CALL CURSOR(X)'.


  SCREENA
  SCREENB

  These are two full screens which you can display in an instant.  They can be
  created with SUBMERGE's screen editor or menu generator (or any other such
  program) and are stored in high memory along with the subroutines.  To print
  the screen, 'CALL SCREENA' or 'CALL SCREENB'.


  SCROLL

  To scroll protect up to 7 lines at the top of the screen, assign a value   
  of 1-7 to an integer and use that integer as a parameter.  As an example,
  'L=4 : CALL SCROLL(L)'.  To remove scroll protection, use a value of 0 (zero)
  for your parameter or 'CALL SCROLL(NO)'.


  STRING

  This is the most powerful and versatile of the routines.  It allows you to
  format an input field, specify valid input characters and specify whether or
  not you require the field to be filled before input ends.  It requires three


                                        2











  parameters.  The first is the format string, which specifies the input field.
  This string will also contain the actual input after the routine returns.
  PLEASE NOTE that this string should not be a string literal - that is, one
  which is assigned a constant, such as 'A$="........"'.  Instead use a state-
  ment such as 'A$=STRING$(4,".")' or 'A$="...."+"...."'.  This is important,
  as string constants are stored in the actual program and this could alter or
  destroy your program.  The next parameter is the valid character string,
  which contains all of the characters that your routine will accept as input
  (BACKSPACE and ENTER are always accepted).  Finally you must specify YES or
  NO as to whether or not you require the field to be filled.  Before calling
  the routine, print the format string and place the cursor over the first
  character in the string which is an actual field character.

  The following examples should clarify this routine:

     10 DEFINT A-Z : TEL$="(...) ...-"+"...." : NUM$="0123456789"
     20 CLS : PRINT@ 320, "TELEPHONE NUMBER ";TEL$ : PRINT@ 338, "";
     30 CALL STRING(TEL$,NUM$,YES)

  This will print 'TELEPHONE NUMBER (...) ...-....' on the 5th line of the
  screen, position the cursor on the first '.' and wait for input.  Only the
  numbers 0-9 and the BACKSPACE key will be accepted.  The ENTER key can only
  be pressed after all the digits have been filled in.  At that time TEL$ will
  contain the telephone number which was entered.

     10 NAM$=STRING$(30,143) : OK$="ABCDEFGHIJKLMNOPQRSTUVWXYZ' "
     20 CLS : PRINT "NAME: ";NAM$ : PRINT@ 6, ""; : CALL CAPS(YES%)
     30 CALL STRING(NAM$,OK$,NO%)

  This will print 'NAME: ', followed by 30 block characters.  The cursor will
  be positioned over the first block character, waiting for input.  Only the
  upper case letters, the apostrophe, the SPACE key and the BACKSPACE key will
  be accepted.  The ENTER key can be pressed at any time to end the input, at
  which time NAM$ will contain the name which was entered.  Note the use of
  'CALL CAPS(YES%)' in line 20 to match the input required by OK$.

                       ------------------------------


                               MENU GENERATOR


  While the above routines can be called from a BASIC program, SUBMERGE also
  offers two convenient features which can be selected from the main menu.  One
  of them is the menu generator.  Upon selecting this feature you will be
  prompted for a title and up to 7 menu selections.  Pressing the BREAK key at
  at any time will then produce a menu similar to SUBMERGE's main menu.  At
  this time you will automatically enter the screen editor, so that you can
  make any changes if you so desire.  Pressing SHIFT + CLEAR will exit the
  screen editor and you will be prompted to store the menu in memory or in a
  disk file.  This menu can then be printed instantly from your BASIC program
  by using 'CALL SCREENA' or 'CALL SCREENB', depending on where you store it.


                                        3












                               SCREEN EDITOR


  Another useful feature is SUBMERGE's screen editor, which can be selected
  from the main menu.  You will be prompted as to whether you want a new screen
  or to revise a screen, etc.  After answering these prompts you will be placed
  in the screen editor.  The editor has two modes -- character and graphics.
  It begins in the character mode, where the keys will function normally.  You
  will note that the cursor is an underline character.  Entering the graphics
  mode is accomplished by pressing the F1 key, which acts as a toggle between
  the two modes.  The cursor is now a full block character.  Now the graphics
  characters can be produced by pressing a single key.  To find out which key
  produces which graphics character, press the F2 key to display a help screen.
  Pressing F2 again returns your screen.  In either mode the arrow keys move
  the cursor around the screen without destroying characters under them.  By
  using the SHIFT key with the arrow keys your screen, instead of the cursor,
  is shifted in the direction of the arrow.  Pressing the F3 key at any time
  will print the current position of the cursor in the upper left corner of the
  screen.  Pressing F3 again will return your screen to normal.

  To exit the screen editor, press SHIFT + CLEAR.  You will be prompted as to
  where you want the screen to be stored.  A sample screen (SAMPLE/SCR) has
  been provided to give you some idea of what you can produce with the screen
  editor.

                       ------------------------------


                            INSTALLING SUBMERGE


  First, prepare the system diskette which you will be using with your BASIC
  program.  Any other machine programs which load into memory above X'FEF5'
  can be loaded at this time.  Otherwise load the program after SUBMERGE has
  been installed.  From 'TRSDOS Ready', type and enter 'SUBMERGE'.  While the
  screen says 'PRESS ANY KEY TO BEGIN', actually pressing 'A' will make it do
  its thing again.  Using the screen editor, place any screens you might be
  using into memory (SCREEN A and SCREEN B).  From SUBMERGE's main menu select
  option < 3 >  CONFIGURE DISK.  When prompted, place your prepared system
  diskette into drive 0 and press ENTER.  The disk is now ready to go.

  The only thing needed now is to use SUBMERGE/BAS with your BASIC program.  If
  you are writing a new program, start with SUBMERGE/BAS.  If you are planning
  to include it in a program you have already written, load the program and use
  the command 'MERGE "SUBMERGE/BAS"'.  This is a short program which assigns
  routine addresses to the routine variables.  It occupies lines 1-5, but with
  the remarks removed it takes up only 2 lines.  These lines can be renumbered,
  but note that they should be at or near the beginning of your program.  If
  this is a problem then add 'RETURN' at the end and call it as a subroutine
  from the beginning of your program.


                                        4






  